Add a GUI builder for the existing ReplaceBlocks field - #603

Summary

This PR extends the existing ReplaceBlocks field with a structured JavaFX rule builder, diagnostics, non-mutating preview, contextual source filters, and release-safety hardening while preserving the advanced text workflow and legacy syntax.

Main additions:

• a visible rule builder integrated into Change NBT;
• explicit regex(...), literal(...), and props(...) source modes;
• source-side tile(...), no_tile(...), y(...), and biome(...) filters;
• per-rule preview counts, overlap warnings, and tile/block-entity estimates;
• five manually selectable block-state catalogues:
  • Java 1.18.2
  • Java 1.20.6
  • Java 1.21.9
  • Java 1.21.11
  • Java 26.2
• versionless editable presets;
• Builder restoration, transactional close/reset behavior, validation, localization, keyboard navigation, and popup performance/geometry fixes;
• safer region failure handling, adjacent relighting, heightmap updates, and duplicate target block-entity cleanup.

Approximately 91k of the 104.5k added lines are generated block-state catalogue JSON from Mojang server reports.

AI-assisted development

This feature, including the ReplaceBlocks Builder and related safety, testing, and documentation work, was developed with substantial assistance from OpenAI Codex.

AI assistance was used for implementation, debugging, test generation, performance analysis, cross-platform investigation, documentation, and code review. I defined the requirements and compatibility/safety boundaries, reviewed the resulting changes, and performed the manual UI and copied-world validation described below.

Compatibility

This preserves the existing ReplaceBlocks text contract:

• legacy bare and quoted sources remain regex-compatible;
• bare source block-state SNBT remains exact-state matching;
• advanced text input remains available;
• catalogue membership is advisory and does not restrict future or modded resource locations;
• catalogues do not automatically migrate block IDs;
• catalogue selection remains manual and newest-by-default;
• unsupported contextual rules fail closed on pre-1.18 formats.

No automatic world-version detection or cross-version ID conversion is introduced.

Safety

• Preview paths do not call replacement or save APIs.
• ReplaceBlocks-only processing failures abort that region before it reaches the save/relight stage.
• Changed chunks are published only after the region save succeeds.
• Adjacent relighting only touches existing region files and does not create POI or entities sidecars.
• Preset persistence failures roll back the in-memory mutation.
• Modern preview and execution share the same source matching rules.
• Duplicate target block entities are removed before replacement tile data is added.

Suggested review order

Because this is an end-to-end feature, I suggest reviewing it in this order:

1. parser, field compatibility, and diagnostics;
2. preview/execution parity and region-save safety;
3. Builder, catalogues, and presets;
4. JavaFX popup/navigation/performance behavior;
5. translations, tests, and user documentation.

The generated catalogue JSON can be reviewed separately from the handwritten code.

Validation

Final branch:

• 173 automated tests passed;
• build and shadowJar passed on the final source tree;
• Windows jpackage app-image passed;
• the packaged runtime completed --help with exit code 0;
• final From/To/Biome popup, keyboard, empty-Biome repetition, popup framing, catalogue reset, and transactional-close checks passed manually.

GitHub-hosted matrix on commit 41d6a127:

• Windows tests, build, shadow JAR, and app-image jpackage passed;
• macOS Intel and ARM DMG builds passed;
• Linux x64/ARM64 DEB and RPM builds passed.

The Windows workflow later reports HTTP 401 while downloading the restricted Querz/build-tools release in this fork. The Windows build and app-image package had already completed; this appears to require upstream repository credentials rather than a source change.

Additional validation included:

• copied Java 1.18 and 1.21 worlds;
• DataVersion 2860 and 4671;
• a 26.3 snapshot copied-world load;
• real biome-boundary replacement;
• adjacent-region relighting;
• Minecraft load/save/reload and game-log review;
• low-end physical-device performance testing;
• KDE/Linux Builder interaction testing.

A physical macOS UI interaction pass was not available; macOS Intel/ARM compilation, tests, and DMG packaging passed in GitHub Actions.

Documentation

Concise syntax, compatibility, and safety documentation is included in docs/REPLACE_BLOCKS.md.

If this feature is accepted, I would also be happy to adapt that documentation into the MCA Selector wiki according to the maintainer's preferred structure.

Out of scope

• automatic catalogue selection from a loaded world;
• cross-version block-ID migration;
• replacing JavaFX VirtualFlow with pagination or a custom list;
• upgrading JavaFX as part of this PR;
• unrelated Gradle packaging modernization.